~ chicken-core (chicken-5) /manual/Module (chicken port)
Trap1[[tags: manual]]2[[toc:]]34== Module (chicken port)56This module contains various extended port definitions.78All errors related to failing port operations will signal a condition9of kind {{exn}}.1011* New in CHICKEN 5.4.0: Errors caused by underlying C calls that12 change errno will produce a condition object with an {{errno}}13 property, which can be accessed with14 {{(get-condition-property <the-condition-object> 'exn 'errno)}}.1516=== Port attributes1718==== port-name1920<procedure>(port-name [PORT])</procedure>2122Fetch filename from {{PORT}}. This returns the filename that was used to open23this file. Returns a special tag string, enclosed into parentheses for24non-file ports. {{PORT}} defaults to the value of {{(current-input-port)}}.252627==== port-position2829<procedure>(port-position [PORT])</procedure>3031Returns the current position of {{PORT}} as two values: row and column number.32If the port does not support such an operation an error is signaled. This33procedure is currently only available for input ports. {{PORT}} defaults to the34value of {{(current-input-port)}}.353637==== set-port-name!3839<procedure>(set-port-name! PORT STRING)</procedure>4041Sets the name of {{PORT}} to {{STRING}}.424344=== Setting the file buffering mode4546==== set-buffering-mode!4748<procedure>(set-buffering-mode! PORT MODE [BUFSIZE])</procedure>4950Sets the buffering-mode for the file associated with {{PORT}} to51{{MODE}}, which should be one of the keywords {{#:full}},52{{#:line}} or {{#:none}}. If {{BUFSIZE}} is specified it53determines the size of the buffer to be used (if any).5455This procedure doesn't work on custom ports, such as those created with {{make-input-port}} or {{make-output-port}}.5657=== Terminal ports5859==== terminal-name6061<procedure>(terminal-name PORT)</procedure>6263Returns the name of the terminal that is connected to {{PORT}}.6465On Windows, this procedure always raises an exception.6667==== terminal-port?6869<procedure>(terminal-port? PORT)</procedure>7071Returns {{#t}} if {{PORT}} is connected to a terminal and72{{#f}} otherwise.737475==== terminal-size7677<procedure>(terminal-size PORT)</procedure>7879Returns two values, the number of rows and columns of the terminal80that is connected to {{PORT}} or {{0}}, {{0}} if the terminal size can81not be obtained.8283On Windows, this procedure always raises an exception.848586=== Input/output port extensions8788==== with-output-to-port8990<procedure>(with-output-to-port PORT THUNK)</procedure>9192Call procedure {{THUNK}} with the current output-port temporarily93bound to {{PORT}}.9495==== make-input-port9697<procedure>(make-input-port READ-CHAR CHAR-READY? CLOSE [PEEK-CHAR [READ-STRING! [READ-LINE]]])</procedure>9899Returns a custom input port. Common operations on this port are100handled by the given parameters, which should be procedures of no101arguments. The following arguments are all different kinds of reader102procedures:103104* {{READ-CHAR}} is the most fundamental reader, and must always be105present. It is a thunk which is called when the next character is106to be read and it should return a character or {{#!eof}}.107* {{CHAR-READY?}} is a thunk which is called when {{char-ready?}}108is called on this port and should return {{#t}} or {{#f}}.109* {{CLOSE}} is a thunk which is called when the port is closed.110* {{PEEK-CHAR}} is a thunk which is called when {{peek-char}} is111called on this port and should return a character or {{#!eof}}. If it112is not provided or {{#f}}, {{READ-CHAR}} will be used instead and the113created port object handles peeking automatically (by calling {{READ}}114and buffering the character).115* {{READ-STRING!}} is called when {{read-string!}} is called (or the116higher-level non-mutating {{read-string}}). It will be invoked with 4117arguments: the port created by {{make-input-port}}, the number of118bytes to read, a string (or sometimes a blob) to read into (which may be119assumed to be big enough to hold the data) and the offset into the120buffer at which to put the data to read. It should return the number121of bytes that have successfully been read, which should always be122equal to the requested bytes unless EOF was hit, in which case it can123be less. If this procedure is not provided or {{#f}}, the buffer will124be filled by repeated reads to {{READ-CHAR}}.125* {{READ-LINE}} is called when {{read-line}} is called. It will be126invoked with two arguments: the port created by {{make-input-port}}127and the maximum number of characters to read (or {{#f}}). If this128procedure is not provided or {{#f}}, the buffer will be filled by129repeated reads to {{READ-CHAR}}.130131All the optional procedures except for {{PEEK-CHAR}} are responsible132for updating the port's position, which currently can only be done via133low-level slot accessors like {{##sys#setslot}}; slot 4 is the row134number (ie, the line) and slot 5 is the column number (ie, the135character on the line). If the port's positions are not updated,136{{port-position}} won't work.137138139==== make-output-port140141<procedure>(make-output-port WRITE CLOSE [FLUSH])</procedure>142143Returns a custom output port. Common operations on this port are handled144by the given parameters, which should be procedures. {{WRITE}} is145called when output is sent to the port and receives a single argument,146a string. {{CLOSE}} is called when the port is closed and should147be a procedure of no arguments. {{FLUSH}} (if provided) is called148for flushing the output port.149150151==== with-error-output-to-port152153<procedure>(with-error-output-to-port PORT THUNK)</procedure>154155Call procedure {{THUNK}} with the current error output-port156temporarily bound to {{PORT}}.157158159==== with-input-from-port160161<procedure>(with-input-from-port PORT THUNK)</procedure>162163Call procedure {{THUNK}} with the current input-port temporarily164bound to {{PORT}}.165166167=== String-port extensions168169==== call-with-input-string170171<procedure>(call-with-input-string STRING PROC)</procedure>172173Calls the procedure {{PROC}} with a single argument that is a174string-input-port with the contents of {{STRING}}.175176177==== call-with-output-string178179<procedure>(call-with-output-string PROC)</procedure>180181Calls the procedure {{PROC}} with a single argument that is a182string-output-port. Returns the accumulated output-string.183184185==== with-input-from-string186187<procedure>(with-input-from-string STRING THUNK)</procedure>188189Call procedure {{THUNK}} with the current input-port temporarily190bound to an input-string-port with the contents of {{STRING}}.191192193==== with-output-to-string194195<procedure>(with-output-to-string THUNK)</procedure>196197Call procedure {{THUNK}} with the current output-port temporarily198bound to a string-output-port and return the accumulated output string.199200==== with-error-output-to-string201202<procedure>(with-error-output-to-string THUNK)</procedure>203204Call procedure {{THUNK}} with the current error output-port205temporarily bound to a string-output-port and return the accumulated206output string.207208209=== Port iterators210211==== port-for-each212213<procedure>(port-for-each FN THUNK)</procedure>214215Apply {{FN}} to successive results of calling the zero argument procedure {{THUNK}} (typically {{read}}) until it returns {{#!eof}}, discarding the results.216217==== port-map218219<procedure>(port-map FN THUNK)</procedure>220221Apply {{FN}} to successive results of calling the zero argument procedure {{THUNK}} (typically {{read}}) until it returns {{#!eof}}, returning a list of the collected results.222223==== port-fold224225<procedure>(port-fold FN ACC THUNK)</procedure>226227Apply {{FN}} to successive results of calling the zero argument procedure {{THUNK}}, (typically {{read}}) passing the {{ACC}} value as the second argument. The {{FN}} result becomes the new {{ACC}} value. When {{THUNK}} returns {{#!eof}}, the last {{FN}} result is returned.228229==== copy-port230231<procedure>(copy-port FROM TO [READ [WRITE]])</procedure>232233Reads all remaining data from port {{FROM}} using the reader procedure234{{READ}} and writes it to port {{TO}} using the writer procedure235{{WRITE}}. {{READ}} defaults to {{read-char}} and {{WRITE}} to236{{write-char}}. Note that this procedure does not check {{FROM}} and237{{TO}} for being ports, so the reader and writer procedures may238perform arbitrary operations as long as they can be invoked239as {{(READ FROM)}} and {{(WRITE X TO)}}, respectively.240{{copy-port}} returns an undefined value.241242{{copy-port}} was introduced in CHICKEN 4.6.0.243244=== Funky ports245246==== make-bidirectional-port247248<procedure>(make-bidirectional-port INPUT-PORT OUTPUT-PORT)</procedure>249250Returns a joint input/output port that proxies port operations to the251given {{INPUT-PORT}} and {{OUTPUT-PORT}}, respectively. This port252satisfies both {{input-port?}} and {{output-port?}}, and its two253directions may be closed independently.254255==== make-broadcast-port256257<procedure>(make-broadcast-port PORT ...)</procedure>258259Returns a custom output port that emits everything written into it to260the ports given as {{PORT ...}}. Closing the broadcast port does not close261any of the argument ports.262263==== make-concatenated-port264265<procedure>(make-concatenated-port PORT1 PORT2 ...)</procedure>266267Returns a custom input port that reads its input from {{PORT1}}, until it268is empty, then from {{PORT2}} and so on. Closing the concatenated port269does not close any of the argument ports.270271272---273Previous: [[Module (chicken plist)]]274275Next: [[Module (chicken pretty-print)]]